Skip to content

Add an optimization doc on TPU #21155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 26 commits into
base: main
Choose a base branch
from
Open

Conversation

bvrockwell
Copy link
Contributor

@bvrockwell bvrockwell commented Jul 18, 2025

Creating a place in the docs for TPU optimization tips, WIP

@bvrockwell bvrockwell requested a review from hmellor as a code owner July 18, 2025 00:52
Copy link

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors. You can run other CI tests on top of those by going to your fastcheck build on Buildkite UI (linked in the PR checks section) and unblock them. If you do not have permission to unblock, ping simon-mo or khluu to add you in our Buildkite org.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

🚀

@mergify mergify bot added documentation Improvements or additions to documentation tpu Related to Google TPUs labels Jul 18, 2025
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds a new documentation page with optimization tips for using vLLM on TPUs. The content is valuable and well-structured. I've identified a few issues, mainly related to broken or fragile links and a missing image, which could impact the user experience. I've also found a typo in a command-line argument that could cause issues for users who copy-paste it. Please see my detailed comments.

@bvrockwell bvrockwell marked this pull request as draft July 18, 2025 00:53
bvrockwell and others added 11 commits July 17, 2025 17:56
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
@bvrockwell bvrockwell marked this pull request as ready for review July 23, 2025 19:34
@bvrockwell
Copy link
Contributor Author

@Chenyaaang @yaochengji ptal

Copy link
Collaborator

@yaochengji yaochengji left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the awesome documentation! Left a few comments!


Although the first compilation can take some time, for all subsequent server launches, vLLM can load these graphs directly from the cache, eliminating the compilation time for future runs.

Use `VLLM_XLA_CACHE_PATH` environment variable to write to shareable storage for future launches.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to mention that there's actually a issue in persistent compilation cache?

Copy link
Member

@hmellor hmellor left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the docs contribution!

I have some general style comments initially:

  • Please fix the pre-commit and DCO checks
  • Please avoid using bold text in the headings
  • Some of the headings are quite long might not render how it was intended
    image
  • In the navigation bar this page is nested in a TPU directory and you only see the title of the page if you try and look inside it
    image

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why docs/configuration/tpu/README.md instead of docs/configuration/tpu.md

#### **SPMD**
More details to come.

#### Want us to cover something that isn't listed here? Open up an issue please and cite this doc. We'd love to hear your questions or tips.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should't be a heading, the whole thing appears in the ToC


### **Get started**

Looking for setup and installation instructions? Find them [here](https://docs.vllm.ai/en/latest/getting_started/installation/google_tpu.html).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use relative md links for internal docs references (http links will break in future releaes)


#### **Profiling**

The auto-tuner provides a profile of optimized configurations as its final step. However, interpreting this profile can be challenging for new users. We plan to expand this section in the future with more detailed guidance. In the meantime, you can learn how to collect a TPU profile using vLLM's native profiling tools [here](https://docs.vllm.ai/en/latest/examples/offline_inference/profiling_tpu.html). This profile can provide valuable insights into your workload's performance.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use relative md links for internal docs references (http links will break in future releaes)

Comment on lines 74 to 79
### **If possible, use the precision that matches the chip’s hardware acceleration**

- v5e has int4/int8 hardware acceleration in the MXU
- v6e has int4/int8 hardware acceleration in the MXU

### **Don't set TP to be less than the number of chips on a single-host deployment**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These headings are also quite long

Copy link
Collaborator

@yaochengji yaochengji left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!
Could you fix the pre-commit and DCO? https://docs.vllm.ai/en/latest/contributing/index.html#code-quality

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation tpu Related to Google TPUs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants